This PR introduces Maybe.Toolkit, a new library that extends the Maybe ecosystem with fluent, exception-free wrappers for common .NET operations that typically throw exceptions. The toolkit provides a functional programming alternative to traditional try-catch blocks while maintaining the elegant patterns of the Maybe library.

Completed Features

Based on feedback from @lucafabbri, the following improvements have been implemented:

• Initial implementation of Maybe.Toolkit components
• Complete HttpToolkit with all HTTP verbs (GET, POST, PUT, PATCH, DELETE)
• Add JSON-integrated HTTP methods (TryGetJsonAsync, TryPostJsonAsync, etc.)
• Add comprehensive tests for new HTTP methods (161 total tests)
• Add integration tests using DummyJSON service to verify success paths
• Significantly improve test coverage from 43% to 52.5% with 69 additional comprehensive tests
• Update demo to showcase new functionality
• Document new features

What's New

🛠️ Complete HTTP Toolkit

HttpToolkit - Safe HTTP client operations with full HTTP verb support:

// All HTTP verbs supported
await client.TryGetAsync("https://api.example.com/users")
    .IfSome(response => ProcessResponse(response))
    .ElseDo(error => HandleError(error));

await client.TryPostAsync("https://api.example.com/users", content)
    .IfSome(response => Console.WriteLine("Created!"))
    .ElseDo(error => HandleError(error));

await client.TryPutAsync("https://api.example.com/users/1", content)
    .IfSome(response => Console.WriteLine("Updated!"))
    .ElseDo(error => HandleError(error));

await client.TryPatchAsync("https://api.example.com/users/1", content)
    .IfSome(response => Console.WriteLine("Patched!"))
    .ElseDo(error => HandleError(error));

await client.TryDeleteAsync("https://api.example.com/users/1")
    .IfSome(response => Console.WriteLine("Deleted!"))
    .ElseDo(error => HandleError(error));

JSON-Integrated HTTP Methods - Seamless integration with JsonToolkit:

// GET and deserialize JSON in one operation
await client.TryGetJsonAsync<User>("https://api.example.com/users/1")
    .IfSome(user => Console.WriteLine($"Hello, {user.Name}!"))
    .ElseDo(error => 
    {
        if (error.IsHttpError) HandleHttpError(error.HttpError);
        if (error.IsJsonError) HandleJsonError(error.JsonError);
    });

// POST JSON and get JSON response
var newUser = new User { Name = "John", Email = "john@example.com" };
await client.TryPostJsonAsync<User, User>("https://api.example.com/users", newUser)
    .IfSome(createdUser => Console.WriteLine($"Created user: {createdUser.Id}"))
    .ElseDo(error => HandleError(error));

// PUT/PATCH JSON operations
await client.TryPutJsonAsync("https://api.example.com/users/1", updatedUser)
    .IfSome(response => Console.WriteLine("User updated"))
    .ElseDo(error => HandleError(error));

🎯 Enhanced Error Handling

HttpJsonError - Composite error type for HTTP+JSON operations:

.ElseDo(error => 
{
    if (error.IsHttpError)
        Console.WriteLine($"HTTP Error: {error.HttpError.StatusCode}");
    else if (error.IsJsonError)
        Console.WriteLine($"JSON Error: {error.JsonError.Message}");
});

🔧 Cross-Platform Compatibility

• PATCH Support: Works on both .NET Standard 2.0 and .NET 8.0+
  • .NET 8.0+: Uses native HttpClient.PatchAsync()
  • .NET Standard 2.0: Uses HttpRequestMessage with PATCH method
• Full HTTP Verb Coverage: GET, POST, PUT, PATCH, DELETE
• JSON Integration: Combines HTTP operations with JSON serialization/deserialization

🧪 Comprehensive Testing & Coverage

Significantly Improved Test Coverage - From 43% to 52.5%:

• 161 total tests (69 new comprehensive tests added)
• Real-world integration tests using DummyJSON service to verify success paths
• Edge case coverage for all toolkit components:
  • FileToolkit: Tests for null paths, readonly files, encoding issues, permissions
  • JsonToolkit: Tests for null inputs, custom options, circular references, UTF-8 bytes
  • ParseToolkit: Tests for all primitive types, custom cultures, hex numbers, null inputs
  • CollectionToolkit: Tests for null collections, out-of-bounds access, readonly collections
  • HttpToolkit: Tests for all HTTP verbs, JSON integration, error scenarios
• Error class coverage: Direct testing of error class properties and constructors
• Cross-platform scenarios: Validation across .NET Standard 2.0 and .NET 8.0

📦 Other Toolkit Components

JsonToolkit - Safe JSON operations using System.Text.Json:

JsonToolkit.TryDeserialize<Person>(json)
    .IfSome(person => Console.WriteLine($"Hello, {person.Name}!"))
    .ElseDo(error => Console.WriteLine($"JSON error: {error.Message}"));

FileToolkit - Safe file I/O operations:

FileToolkit.TryReadAllText("config.json")
    .IfSome(content => ProcessConfig(content))
    .ElseDo(error => LogError($"File error: {error.Message}"));

ParseToolkit - Safe parsing for common types:

ParseToolkit.TryParseInt(userInput)
    .IfSome(number => Calculate(number))
    .ElseDo(error => ShowValidationError());

CollectionToolkit - Safe collection access:

dictionary.TryGetValue("key")
    .IfSome(value => UseValue(value))
    .ElseDo(error => HandleMissingKey());

✅ Quality Assurance

• All existing tests continue to pass (174 core tests)
• 161 comprehensive unit and integration tests covering success and failure scenarios
• 52.5% code coverage for Maybe.Toolkit (significantly improved from 43%)
• Real-world integration tests using DummyJSON service to verify success paths
• Working demo program validates real-world usage patterns including all HTTP verbs
• Cross-platform compatibility tested for .NET Standard 2.0 and .NET 8.0
• Follows existing Maybe library conventions and patterns

🚀 Benefits

1. Complete HTTP Coverage - All HTTP verbs supported with consistent patterns
2. JSON Integration - Seamless combination of HTTP and JSON operations
3. Comprehensive Testing - High-quality test coverage with real-world scenarios
4. Real-world Validation - Integration tests verify actual API interactions work
5. Eliminates Exception Handling - No more verbose try-catch blocks
6. Fluent API - Chain operations naturally with IfSome, ElseDo, Select
7. Type Safety - Compile-time guarantees that errors are handled
8. Consistent Patterns - Unified approach across different operation types
9. Functional Style - Embrace functional programming in .NET
10. Composable - Easy integration with existing Maybe operations

Breaking Changes

None. This is a purely additive feature that doesn't modify existing functionality.

Migration Guide

No migration needed. Simply add the FluentCoder.Maybe.Toolkit NuGet package to start using the new functionality alongside existing Maybe patterns.

This implementation addresses all feedback from @lucafabbri, providing complete HTTP verb coverage, seamless JSON integration, and comprehensive integration testing using the DummyJSON service. The test coverage has been significantly improved with 69 additional tests covering edge cases, error scenarios, and real-world usage patterns.

This pull request was created as a result of the following prompt from Copilot chat.

L'obiettivo di questa attività è espandere l'ecosistema della libreria Maybe creando una nuova libreria a sé stante, denominata "Toolkit".

Questa libreria fornirà una serie di wrapper per operazioni comuni del framework .NET che notoriamente lanciano eccezioni (ad esempio, JsonSerializer, operazioni su file, parsing di stringhe). Lo scopo è quello di offrire un'alternativa fluente e funzionale alla gestione tradizionale try-catch, sfruttando il tipo Maybe<TValue, TResult>.

Attività Principali:

Verranno sviluppati i seguenti componenti, ognuno dei quali gestirà le eccezioni comuni e le incapsulerà in un Maybe:

1. Wrapper per System.Text.Json.JsonSerializer: Metodi TryDeserialize che restituiscano un Maybe invece di lanciare JsonException.
2. Wrapper per System.IO.File: Metodi come TryReadAllText o TryReadAllBytes che gestiscano IOException, FileNotFoundException, ecc.
3. Wrapper per metodi di parsing: Alternative Try per int.Parse, double.Parse, Guid.Parse che gestiscano la FormatException.
4. Wrapper per System.Net.Http.HttpClient: Estensioni per HttpClient (es. TryGetAsync) che catturino HttpRequestException.
5. Wrapper per l'accesso a collezioni: Metodi di estensione sicuri per dizionari e liste per prevenire KeyNotFoundException o ArgumentOutOfRangeException.

Requisiti:

• Il "Toolkit" dovrà essere un progetto di libreria separato.
• Un progetto di test unitari dedicato dovrà essere creato per garantire un'adeguata copertura del codice dei nuovi componenti.

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.